home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / djgpp / tktdoc / socklib.doc < prev    next >
Text File  |  1994-08-11  |  28KB  |  1,143 lines
  1. THE BERKELEY SOCKET LIBRARY
  2.  
  3. In order for applications to communicate with each other, whether
  4. on the same machine or different machines across a network, the Berkeley
  5. Socket Interface was chosen as the means to accomplish this in the
  6. DESQview/X environment.
  7.  
  8. The reasons for this are clear. The Berkeley Socket Interface is the
  9. standard which other X Window systems and UNIX systems use to communicate.
  10. In addition, it is network independent--in fact, a network need
  11. not be present on a standalone system. DESQview/X uses the Berkeley
  12. Socket Interface 4.3, or BSD 4.3. This release includes two different
  13. types of communication--stream (TCP) and datagram (UDP). DESQview/X,
  14. through its BSD 4.3 routines, supports both of these types.
  15.  
  16. DESQview/X supplies both the include files necessary to compile an
  17. application that uses BSD 4.3 as well as a socket library that performs
  18. the low level functions. The include files needed are specified in
  19. each function's synopsis. The socket library is included in the DESQview/X
  20. System Library (sys.lib) which should be linked into your application.
  21. Since the Berkeley Socket Interface is a well-defined (and expansive)
  22. interface, this document does not attempt to teach a user how to use
  23. BSD 4.3 Sockets--there is plenty of material that does this already.
  24. See Chapter 1: Introduction for additional information.
  25. Instead, each of the BSD 4.3 Socket routines that are supported in
  26. DESQview/X will now be listed in reference form.
  27.  
  28. Supported
  29.  
  30. BSD 4.3
  31.  
  32. Socket Routines
  33.  
  34.  gethostbyaddr
  35.  
  36. SYNOPSIS
  37.  
  38. #include <sys/types.h>
  39. #include <sys/socket.h>
  40. #include <netdb.h>
  41. struct hostent *gethostbyaddr(char *addr,int addrLen,int af);
  42.  
  43. DESCRIPTION
  44.  
  45. Searches the local HOSTS file sequentially until an entry is found
  46. with an h_addr_list entry corresponding to the address pointed to
  47. by the 'addr' parameter.
  48.  
  49. Return Values
  50.  
  51. gethostbyaddr returns NULL on failure.
  52.  
  53. Notes
  54.  
  55. The hostent structure is defined in the description of the gethostent
  56. call.
  57.  
  58.  See Also
  59.  
  60. sethostent, gethostent, gethostbyname, endhostent
  61.  
  62.  gethostbyname
  63.  
  64. SYNOPSIS
  65.  
  66. #include <sys/types.h>
  67. #include <sys/socket.h>
  68. #include <netdb.h>
  69. struct hostent *gethostbyname(char *name);
  70.  
  71. DESCRIPTION
  72.  
  73. Searches the local HOSTS file sequentially until an entry is found
  74. with an h_name that corresponds to the 'name' parameter.
  75.  
  76. Return Values
  77.  
  78. gethostbyname returns NULL on failure.
  79.  
  80. See Also
  81.  
  82. sethostent, gethostent, gethostbyaddr, endhostent
  83.  
  84.  gethostname
  85.  
  86. SYNOPSIS
  87.  
  88. #include <sys/types.h>
  89. #include <sys/socket.h>
  90. #include <netdb.h>
  91. int gethostname(char *name,int nameLen);
  92.  
  93. DESCRIPTION
  94.  
  95. gethostname retrieves the name of the local host. The 'name' parameter
  96. is a buffer of maximum size designated by the 'nameLen' parameter.
  97. The buffer will be filled with a null-terminated string unless insufficient
  98. space is available.
  99.  
  100. Return Values
  101.  
  102. gethostname returns bytes filled on
  103.  
  104. success, -1 on failure.
  105.  
  106.  setservent
  107.  
  108. SYNOPSIS
  109.  
  110. #include <netdb.h>
  111. void setservent(int stayopen);
  112.  
  113. DESCRIPTION
  114.  
  115. setservent opens and rewinds the local SERVICES file. This call is
  116. primarily useful for resetting the SERVICES file to the first entry
  117. in preparation for calls to getservent. The stayopen parameter is
  118. currently ignored.
  119.  
  120. See Also
  121.  
  122. endservent, getservent, getservbyport, getservbyname
  123.  
  124.  getservent
  125.  
  126. SYNOPSIS
  127.  
  128. #include <netdb.h>
  129. struct servent *getservent(void);
  130.  
  131. DESCRIPTION
  132.  
  133. getservent reads the next entry in the local SERVICES file, opening
  134. the file if necessary. The return value is a pointer to a structure
  135. containing the broken-out fields of a line from the SERVICES file.
  136. The structure definition is as follows:
  137.  
  138. struct servent
  139. {
  140. char *s_name;
  141. char **s_aliases;
  142. int s_port;
  143. char *s_proto;
  144. };
  145.  
  146. s_name, The official name of the service.
  147.  
  148. s_aliases A NULL terminated list of alternate names for the
  149. service.
  150.  
  151. s_port, The port number which the service uses. Port numbers
  152. are returned in network short byte order.
  153.  
  154. s_proto The name of the protocol to use when contacting the
  155. service.
  156.  
  157. Return Values
  158.  
  159. getservent returns NULL on failure or EOF.
  160.  
  161. See Also
  162.  
  163. setservent, getservbyname, getservbyport, endservent
  164.  
  165.  
  166.  
  167.  endservent
  168.  
  169. SYNOPSIS
  170.  
  171. #include <netdb.h>
  172. void endservent(void);
  173.  
  174. DESCRIPTION
  175.  
  176. endservent closes the local SERVICES file.
  177.  
  178. See Also
  179.  
  180. setservent, getservent, getservbyport, getservbyname
  181.  
  182.  getservbyname
  183.  
  184. SYNOPSIS
  185.  
  186. #include <netdb.h>
  187. struct servent *getservbyname(char *name,char *proto);
  188.  
  189. DESCRIPTION
  190.  
  191. getservbyname searches the local SERVICES file sequentially until
  192. an entry with the s_name field matching the 'name' parameter is found.
  193. If a non-NULL 'proto' parameter is specified, the search will also
  194. include a match of the s_proto field with the 'proto' parameter.
  195.  
  196. Notes
  197.  
  198. The servent structure is defined in the description of the getservent
  199. call.
  200.  
  201. Return Values
  202.  
  203. getservbyname returns NULL on failure.
  204.  
  205. See Also
  206.  
  207. setservent, getservent, getservbyport, endservent
  208.  
  209.  getservbyport
  210.  
  211. SYNOPSIS
  212.  
  213. #include <netdb.h>
  214. struct servent *getservbyport(int port,char *proto);
  215.  
  216. DESCRIPTION
  217.  
  218. getservbyport searches the local SERVICES file sequentially until
  219. an entry with an s_port matching the 'port' parameter is found. If
  220. a non-NULL 'proto' parameter is specified, the search will also include
  221. a match of the s_proto field with the 'proto' parameter.
  222.  
  223. Notes
  224.  
  225. The servent structure is defined in the description of the getservent
  226. call.
  227.  
  228. Return Values
  229.  
  230. getservbyport returns NULL on failure.
  231.  
  232. See Also
  233.  
  234. setservent, getservent, getservbyname, endservent
  235.  
  236.  getprotobyname
  237.  
  238. SYNOPSIS
  239.  
  240. #include <netdb.h>
  241. struct protoent *getprotobyname(char *name);
  242.  
  243. DESCRIPTION
  244.  
  245. getprotobyname searches the local PROTOCOLS file sequentially until
  246. an entry is found with a p_name that matches the 'name' parameter.
  247.  
  248.  
  249. Notes
  250.  
  251. The protoent structure is defined in the description of the getprotoent
  252. call.
  253.  
  254. Return Values
  255.  
  256. getprotobyname returns NULL on failure.
  257.  
  258. See Also
  259.  
  260. getprotobynumber
  261.  
  262.  getprotobynumber
  263.  
  264. SYNOPSIS
  265.  
  266. #include <netdb.h>
  267. struct protoent *getprotobynumber(int proto);
  268.  
  269. DESCRIPTION
  270.  
  271. getprotobynumber searches the local PROTOCOLS file sequentially until
  272. an entry is found with a p_proto that matches the 'proto' parameter.
  273.  
  274. Notes
  275.  
  276. The protoent structure is defined in the description of the getprotoent
  277. call.
  278.  
  279. Return Values
  280.  
  281. getprotobynumber returns NULL on failure.
  282.  
  283. See Also
  284.  
  285. getprotobyname
  286.  
  287.  socket
  288.  
  289. SYNOPSIS
  290.  
  291. #include <sys/types.h>
  292. #include <sys/socket.h>
  293. int socket(int af,int type,int protocol);
  294.  
  295. DESCRIPTION
  296.  
  297. socket opens an endpoint for network communication. The af parameter
  298. specifies the address family desired for the socket. The following
  299. address families are supported:
  300.  
  301. AF_INET, Internet addressing family
  302. AF_UNIX, Local (file-type) addressing family
  303.  
  304. The 'type' parameter specifies the method of I/O that will be available
  305. to the socket. SOCK_STREAM and SOCK_DGRAM are supported.
  306.  
  307. SOCK_STREAM type sockets provide connection oriented, stream communications.
  308. Similar to pipes, full duplex, reliable and sequenced delivery is
  309. guaranteed. In order for I/O to occur, the socket must be in a connected
  310. state. Data transfer is accomplished by way of the recv and send calls,
  311. and both blocking and non-blocking modes are supported.
  312.  
  313. SOCK_DGRAM type sockets provide connectionless, datagram (fixed length)
  314. communications. There is no guarantee of reliablity or sequencing.
  315. SOCK_DGRAM sockets need not be in a connected state in order to transmit
  316. or receive data. Data transfer is accomplished by way of the recvfrom
  317. and sendto calls, and both blocking and non-blocking modes are supported.
  318.  
  319. The 'protocol' parameter is ignored at this time.
  320.  
  321. Return Values
  322.  
  323. socket returns a non-negative
  324.  
  325. descriptor on success, -1 on failure (errno as described below).
  326.  
  327. Errors
  328.  
  329. EAFNOSUPPORT, The address family specified is not supported.
  330. EPROTOTYPE, The protocol specified is not supported.
  331. ESOCKTNOSUPPORT, The type specified is not SOCK_STREAM or SOCK_DGRAM
  332. ENOBUFS, The network has exhausted its resources.
  333.  
  334. See Also
  335.  
  336. accept, bind, connect, getsockname, ioctl, listen, recv, select, send,
  337. so_close
  338.  
  339.  so_close
  340.  
  341. SYNOPSIS
  342.  
  343. #include <sys/types.h>
  344. #include <sys/socket.h>
  345. int so_close(int s);
  346.  
  347. DESCRIPTION
  348.  
  349. Closes and frees the socket descriptor referenced by 's'. If the socket
  350. is of type SOCK_STREAM and in a connected state, the connection is
  351. closed, and the remote peer is notified. If the socket is of type
  352. SOCK_STREAM and in a listening state, any connections available for
  353. acceptance will be lost.
  354.  
  355. Return Values
  356.  
  357. so_close returns 0 on success, -1 on failure (errno as described below).
  358.  
  359. Errors
  360.  
  361. ENOTSOCK, The specified descriptor was invalid.
  362.  
  363.  bind
  364.  
  365. SYNOPSIS
  366.  
  367. #include <sys/types.h>
  368. #include <sys/socket.h>
  369. int bind(int s,struct sockaddr *addr,int addrLen);
  370.  
  371. DESCRIPTION
  372.  
  373. Assigns a name to the unnamed socket referenced by 's'. The name bound
  374. to the socket is specified by the 'addr' parameter.
  375.  
  376. Return Values
  377.  
  378. bind returns 0 on success, -1 on failure (errno as described below).
  379.  
  380. Errors
  381.  
  382. ENOTSOCK, Invalid descriptor.
  383. EAFNOSUPPORT, Invalid address family.
  384. EINVAL, Socket is already bound.
  385. EADDRINUSE, A socket is already bound to the address on the
  386. local host.
  387.  
  388.  getsockname
  389.  
  390. SYNOPSIS
  391.  
  392. #include <sys/types.h>
  393. #include <sys\socket.h>
  394. int getsockname(int s,struct sockaddr *name,int *nameLen);
  395.  
  396. DESCRIPTION
  397.  
  398. getsockname returns the name associated with socket s, assigned by
  399. a previous call to bind. The value pointed to by namelen should be
  400. initialized to the size of the buffer pointed to by 'name'. The name
  401. of the socket will be placed into the buffer pointed to by the 'name'
  402. parameter and the value pointed to by the 'namelen' parameter will
  403. be updated to the actual size of the name returned.
  404.  
  405. Return Values
  406.  
  407. getsockname returns 0 on success, -1 on failure (errno as described
  408. below).
  409.  
  410. Errors
  411.  
  412. ENOTSOCK, Invalid descriptor.
  413. EINVAL, Socket is not bound.
  414.  
  415.  ioctl
  416.  
  417. SYNOPSIS
  418.  
  419. #include <sys/types.h>
  420. #include <sys\socket.h>
  421. int ioctl(int s,int req,long *argp);
  422.  
  423. DESCRIPTION
  424.  
  425. Modifies the I/O strategy on the socket specified by 's' to the strategy
  426. indicated by 'req' and value specified by 'argp'. For example, modification
  427. of a socket to a non-blocking I/O strategy would entail a call as
  428. follows:
  429.  
  430. nonBlocking = 1l;
  431.  
  432. ioctl(s, FIONBIO, (long *)&nonBlocking);
  433.  
  434. Return Values
  435.  
  436. ioctl returns 0 on most requests, but may return non-zero values on
  437. success for some operations. On failure, ioctl returns -1 and errno
  438. is set as described below.
  439.  
  440. Errors
  441.  
  442. ENOTSOCK, Invalid descriptor.
  443. EINVAL, Invalid option specified.
  444.  
  445.  select
  446.  
  447. SYNOPSIS
  448.  
  449. #include <sys/types.h>
  450. #include <sys/time.h>
  451. int select(int nfds,struct fd_set *readfds, struct fd_set
  452. *writefds,struct fd_set *exceptfds, struct timeval *timeout);
  453.  
  454. DESCRIPTION
  455.  
  456. The select call examines the bitmasks pointed to by 'readfds', 'writefds'
  457. and 'exceptfds' and determines the readability and writeability of
  458. the sockets specified by the bits in the masks. Each bit position
  459. in the input mask designates the integer value of the socket desired
  460. for evaluation.
  461.  
  462. The 'nfds' parameter indicates the range of selectors to be examined.
  463. The 'timeout' parameter is a pointer to a structure indicating the
  464. time to wait (block) for the selection to complete. A NULL timeout
  465. pointer indicates that the operation should block indefinitely until
  466. the select completes. A poll operation can be undertaken by passing
  467. a pointer to a timeval structure intialized to zero.
  468.  
  469. Although the primary uses of select include determining whether a
  470. descriptor is readable or writeable, it can also indicate several
  471. conditions. A select can be undertaken on a SOCK_STREAM socket in
  472. a listening state to determine whether a connection is available for
  473. acceptance. This test is performed by setting the bit corresponding
  474. to the socket in the read mask, and determining whether it remains
  475. set following the call. An accept call can then be issued to retrieve
  476. the pending connection. Additionally, select can indicate a dropped
  477. connection on a SOCK_STREAM socket in a connected state. This check
  478. is performed in a manner similar to that for a listening socket (described
  479. above). An immediate recv operation can then be performed to either
  480. retrieve pending data or determine the cause of the failure.
  481.  
  482. Return Values
  483.  
  484. On success, select returns a non-negative indicator of the number
  485. of descriptors successfully examined. A 0 is returned if a timeout
  486. occured. On failure, select returns -1 and errno is set as described
  487. below.
  488.  
  489. Errors
  490.  
  491. EBADF, One of the descriptors specified in the bitmasks is
  492. invalid.
  493.  
  494.   setsockopt
  495.  
  496. SYNOPSIS
  497.  
  498. #include <sys/types.h>
  499. #include <sys/socket.h>
  500. int setsockopt(int s,int level,int name,char *val,int len);
  501.  
  502. DESCRIPTION
  503.  
  504. This call provided for compatibility only.
  505.  
  506.  accept
  507.  
  508. SYNOPSIS
  509.  
  510. #include <sys/types.h>
  511. #include <sys/socket.h>
  512. int accept(int s,struct sockaddr *addr,int *addrLen);
  513.  
  514. DESCRIPTION
  515.  
  516. accept examines the listening socket designated by 's' for pending
  517. connections. The socket must be of type SOCK_STREAM created by a socket
  518. call, bound to an address with bind and is listening for connections
  519. after a listen call. If a connection is available, accept creates
  520. a new socket with the properties of s and returns it to the caller
  521. as the connected socket. The socket designated by 's' is still available
  522. to accept further connections. If no connections are available, and
  523. the socket is marked as non-blocking, an error is returned as described
  524. below. If the socket is marked as blocking, the call blocks until
  525. a connection is available.
  526.  
  527. When a valid connection descriptor is returned, the 'addr' parameter
  528. is filled with the address of the connection partner, up to a length
  529. specified by the value pointed to by 'addrLen'. The value pointed
  530. to by 'addrLen' is then updated to reflect the actual size of the
  531. address.
  532.  
  533. Return Values
  534.  
  535. Like socket, accept returns a non-negative descriptor on success.
  536. On failure, it returns -1 and sets errno as described below.
  537.  
  538. Errors
  539.  
  540. ENOTSOCK, Invalid descriptor.
  541. EWOULDBLOCK, No connections pending.
  542.  
  543. See Also
  544.  
  545. accept, socket
  546.  
  547.  connect
  548.  
  549. SYNOPSIS
  550.  
  551. #include <sys/types.h>
  552. #include <sys/socket.h>
  553. int connect(int s,struct sockaddr *name,int nameLen);
  554.  
  555. DESCRIPTION
  556.  
  557. For SOCK_STREAM type sockets, connect attempts to establish a connection
  558. between the socket specified by 's' and opened with a socket call
  559. and a destination socket opened with socket, bound to the destination
  560. address specified by 'name' and listening for connection requests.
  561. A SOCK_STREAM socket can only be connected once.
  562.  
  563. For SOCK_DGRAM type sockets, connect specifies the destination to
  564. be used for send requests and the only peer from which datagrams can
  565. be received. Provided for convenience, this allows datagram sockets
  566. to use the recv and send calls in addition to recvfrom and sendto.
  567. SOCK_DGRAM sockets can connect multiple times and can dissolve the
  568. current connection by making a call to connect with a NULL destination
  569. name.
  570.  
  571. Return Values
  572.  
  573. connect returns 0 on success, -1 on failure (errno set as described
  574. below).
  575.  
  576. Errors
  577.  
  578. ENOTSOCK, Invalid descriptor.
  579. EAFNOSUPPORT, Invalid address family.
  580. EISCONN, Socket is already connected.
  581. EWOULDBLOCK, Processing connect request.
  582. ECONNREFUSED, Connection refused.
  583. EINPROGRESS, Processing connect request.
  584. ETIMEDOUT, Connection establishment timed out without establishing
  585. a connection.
  586.  
  587. See Also
  588.  
  589. socket, accept, listen, select
  590.  
  591.  listen
  592.  
  593. SYNOPSIS
  594.  
  595. #include <sys/types.h>
  596. #include <sys/socket.h>
  597. int listen(int s,int backlog);
  598.  
  599. DESCRIPTION
  600.  
  601. listen prepares the SOCK_STREAM socket specified by 's', created by
  602. a socket call and bound to an address with bind, to accept connections
  603. made by other SOCK_STREAM sockets calls to connect. The connection
  604. status of the socket may be queried by calls to select, and new connections
  605. are retrieved by calls to accept. The 'backlog' parameter indicates
  606. the number of simultaneous pending connections that can be queued
  607. between accept calls.
  608.  
  609. Return Values
  610.  
  611. listen returns 0 on success, -1 on failure (errno set as described
  612. below).
  613.  
  614. Errors
  615.  
  616. ENOTSOCK, Invalid descriptor.
  617. ECONNREFUSED, Socket not bound or non-stream.
  618. ENOBUFFS, Insufficient resources.
  619.  
  620. See Also
  621.  
  622. socket, accept, select, connect
  623.  
  624.  recv
  625.  
  626. SYNOPSIS
  627.  
  628. #include <sys/types.h>
  629. #include <sys/socket.h>
  630. int recv(int s,char *buffer,int buffLen,int flags);
  631.  
  632. DESCRIPTION
  633.  
  634. recv is used to receive data for a connected socket from its connection
  635. peer. The 'buffer' parameter is filled up to a maximum of 'buffLen'
  636. bytes. If the socket is marked as blocking, the recv call waits until
  637. data is available on the connection. If the socket is marked as non-blocking
  638. the call returns immediately with an error code if no data is available.
  639. This call can be made after a call to select() to determine the readability
  640. of the socket.
  641.  
  642. Notes
  643.  
  644. The 'flags' parameter is ignored.
  645.  
  646. Return Values
  647.  
  648. On success, recv returns a non-negative integer indicating the length
  649. of the data returned in the 'buffer' parameter. On connection termination,
  650. recv returns 0. On errors, recv returns -1 and errno as described
  651. below.
  652.  
  653. Errors
  654.  
  655. ENOTCONN, Connection terminated.
  656. ENOTSOCK, Invalid descriptor or connection failure.
  657. EWOULDBLOCK, No data available.
  658. ESHUTDOWN, Socket shutdown.
  659.  
  660. See Also
  661.  
  662. send, sendto, recvfro
  663.  
  664.  send
  665.  
  666. SYNOPSIS
  667.  
  668. #include <sys/types.h>
  669. #include <sys/socket.h>
  670. int send(int s,const char *buffer,int buffLen,int flags);
  671.  
  672. DESCRIPTION
  673.  
  674. send is used to transmit data for a connected socket to its connection
  675. peer. A maximum number of bytes will be sent corresponding to the
  676. 'buffLen' parameter. If the socket is marked as blocking, the send
  677. call will wait until all data has been sent on the connection. If
  678. the socket is marked as non-blocking, the call returns immediately
  679. with an error code if no data was sent. This call can be made after
  680. a call to select() to determine the writeability of the socket.
  681.  
  682. Notes
  683.  
  684. The 'flags' parameter is ignored.
  685.  
  686. Return Values
  687.  
  688. On success, send returns a non-negative integer indicating the number
  689. of bytes transmitted. On failure, -1 is returned with errno as described
  690. below.
  691.  
  692. Errors
  693.  
  694. ENOTSOCK, Invalid descriptor
  695. EWOULDBLOCK, No send buffer space available.
  696. ENOTCONN, Connection terminated.
  697. ESHUTDOWN, Socket shutdown.
  698.  
  699. See Also
  700.  
  701. sendto, recv, recvfrom
  702.  
  703.  getpeername
  704.  
  705. SYNOPSIS
  706.  
  707. #include <sys/types.h>
  708. #include <sys/socket.h>
  709. int getpeername(int s,struct sockaddr *name, int *nameLen);
  710.  
  711. DESCRIPTION
  712.  
  713. Retrieves the name of the remote peer connected to the socket specified
  714. by 's'. The 'nameLen' parameter is initialized to the maximum space
  715. available in the 'name' parameter, and is updated to reflect the actual
  716. length of the name placed into the 'name' parameter.
  717.  
  718. Return Values
  719.  
  720. getpeername returns 0 on success, -1 on failure (errno as described
  721. below).
  722.  
  723. Errors
  724.  
  725. ENOTSOCK, Invalid descriptor.
  726. ENOTCONN, Socket is not connected.
  727.  
  728.  recvfrom
  729.  
  730. SYNOPSIS
  731.  
  732. #include <sys/types.h>
  733. #include <sys/socket.h>
  734. int recvfrom(int s, char **buffer, int len, int
  735.     flags, struct sockaddr *from, int flen);
  736.  
  737. DESCRIPTION
  738.  
  739. recvfrom is used to receive data for the connected, SOCK_STREAM type
  740. socket or for the SOCK_DGRAM socket specified by 's'.This call is
  741. identical to the recv call with the addition that the 'from' parameter
  742. is filled with the name of the socket sending the data. The 'flen'
  743. parameter is initialized to the maximum size of the buffer pointed
  744. to by from and updated to the actual length of the name placed
  745. into the from buffer.
  746.  
  747. Notes
  748.  
  749. The 'flags' parameter is ignored.
  750.  
  751. Return Values
  752.  
  753. On success, recv returns a non-negative integer indicating the length
  754. of the data returned in the 'buffer' parameter. On connection termination,
  755. recv returns 0. On errors, recv returns -1 and errno as described
  756. below.
  757.  
  758. Errors
  759.  
  760. ENOTCONN, Connection terminated.
  761. ENOTSOCK, Invalid descriptor or connection failure.
  762. EWOULDBLOCK, No data available.
  763. ESHUTDOWN, Socket shutdown.
  764.  
  765. See Also
  766.  
  767. send, sendto, recv
  768.  
  769.  sendto
  770.  
  771. SYNOPSIS
  772.  
  773. #include <sys/types.h>
  774. #include <sys/socket.h>
  775. int sendto(int s, const char *buffer, int len,
  776.     intflags, struct sockaddr *to, int tolen);
  777.  
  778. DESCRIPTION
  779.  
  780. sendto is used to transmit data for the connected, SOCK_STREAM type
  781. socket or for the SOCK_DGRAM socket specified by 's'.This call is
  782. identical to the send call with the addition that the 'to' parameter
  783. indicates the name of the destination socket for SOCK_DGRAM sockets
  784. and is ignored for SOCK_STREAM sockets. The 'tolen' parameter is set
  785. to the size of the buffer to be sent.
  786.  
  787. Notes
  788.  
  789. The 'flags' parameter is ignored.
  790.  
  791. Return Values
  792.  
  793. On success, send returns a non-negative integer indicating the number
  794. of bytes transmitted. On failure, -1 is returned with errno as described
  795. below.
  796.  
  797. Errors
  798.  
  799. ENOTSOCK, Invalid descriptor
  800. EWOULDBLOCK, No send buffer space available.
  801. ENOTCONN, Connection terminated.
  802. ESHUTDOWN, Socket shutdown.
  803.  
  804. See Also
  805.  
  806. send, recv, recvfrom
  807.  
  808.  htonl
  809.  
  810. SYNOPSIS
  811.  
  812. #include <sys/types.h>
  813. #include <netinet/in.h>
  814.  
  815. unsigned long htonl(unsigned long ibmdd); /*
  816. host to network long */
  817. unsigned int htons(unsigned int ibmdw); /* host to network short */
  818.  
  819.  
  820. unsigned long ntohl(unsigned long netdd); /* network to host long
  821. */ unsigned int ntohs(unsigned int netdw); /* network to host short
  822. */
  823.  
  824. DESCRIPTION
  825.  
  826. These routines convert 16 and 32 bit quantities between 80x86 byte
  827. ordering and network byte ordering, and vice-versa. They are most
  828. often used in combination with the SERVICES routines and Internet
  829. address routines.
  830.  
  831.  inet_addr
  832.  
  833. SYNOPSIS
  834.  
  835. #include <sys/types.h>
  836. #include <sys/socket.h>
  837. #include <netinet/in.h>
  838. #include <arpa/inet.h>
  839. unsigned long inet_addr(const char *addrDesc);
  840.  
  841. DESCRIPTION
  842.  
  843. inet_addr returns the network long integer representation of the Internet
  844. '.' notation ASCIIZ string specified by 'addrDesc'.
  845.  
  846. Return Values
  847.  
  848. inet_addr -1 on invalid input string.
  849.  
  850.  inet_lnaof
  851.  
  852. SYNOPSIS
  853.  
  854. #include <sys/types.h>
  855. #include <sys/socket.h>
  856. #include <netinet/in.h>
  857. #include <arpa/inet.h>
  858. unsigned long inet_lnaof(struct in_addr);
  859.  
  860. DESCRIPTION
  861.  
  862. Returns the network byte order long integer value representing the
  863. local address portion of the Internet address specified by 'addr'.
  864.  
  865.  
  866.  inet_makeaddr
  867.  
  868. SYNOPSIS
  869.  
  870. #include <sys/types.h>
  871. #include <sys/socket.h>
  872. #include <netinet/in.h>
  873. #include <arpa/inet.h>
  874. long inet_makeaddr(long net, long lna);
  875.  
  876. DESCRIPTION
  877.  
  878. Combines the network and local address portions specified in network
  879. byte order into a single Internet address.
  880.  
  881.  inet_netof
  882.  
  883. SYNOPSIS
  884.  
  885. #include <sys/types.h>
  886. #include <sys/socket.h>
  887. #include <netinet/in.h>
  888. #include <arpa/inet.h>
  889. ulong inet_netof(struct in_addr);
  890.  
  891. DESCRIPTION
  892.  
  893. Returns the network byte order long integer value representing the
  894. network portion of the Internet address specified by 'addr'.
  895.  
  896.  inet_network
  897.  
  898. SYNOPSIS
  899.  
  900. #include <sys/types.h>
  901. #include <sys/socket.h>
  902. #include <netinet/in.h>
  903. #include <arpa/inet.h>
  904. unsigned long inet_network(const char *cp);
  905.  
  906. DESCRIPTION
  907.  
  908. Converts the Internet '.' notation address specified by 'cp' to an
  909. Internet address and returns the network portion of the address.
  910.  
  911.   inet_ntoa
  912.  
  913. SYNOPSIS
  914.  
  915. #include <sys/types.h>
  916. #include <sys/socket.h>
  917. #include <netinet/in.h>
  918. #include <arpa/inet.h>
  919. char *inet_ntoa(struct in_addr in);
  920.  
  921. DESCRIPTION
  922.  
  923. Converts the Internet address specified by 'in' to an Internet '.'
  924. notation ASCIIZ string representing the address.
  925.  
  926. Notes
  927.  
  928. String is STATIC and will be overwritten with each call.
  929.  
  930.  setpwent
  931.  
  932. SYNOPSIS
  933.  
  934. #include <pwd.h>
  935. void setpwent(void);
  936.  
  937. DESCRIPTION
  938.  
  939. setpwent opens and rewinds the local password file. This call is primarily
  940. useful for resetting the password file to the first entry in preparation
  941. for calls to getpwent.
  942.  
  943.  getpwent
  944.  
  945. SYNOPSIS
  946.  
  947. #include <pwd.h>
  948. struct passwd *getpwent(void);
  949.  
  950. DESCRIPTION
  951.  
  952. getpwent reads the next entry in the local password file, opening
  953. the file if necessary. The return value is a pointer to a structure
  954. containing the broken-out fields of an entry from the password information
  955. file with the structure definition is as follows:
  956.  
  957. struct passwd {
  958.     char *pw_name;
  959.      char *pw_passwd;
  960.      int pw_uid;
  961.      int pw_gid;
  962.      int pw_quota;
  963.      char *pw_comment;
  964.      char *pw_gecos;
  965.      char *pw_dir;
  966.      char *pw_shell;
  967. };
  968.  
  969. pw_name    Official username.
  970. pw_passwd  Encrypted password for the user.
  971. pw_uid     Userid for the user.
  972. pw_gid     Unused at this time.
  973. pw_quota      Unused at this time.
  974. pw_comment Unused at this time.
  975. pw_gecos      Unused at this time.
  976. pw_dir     Home directory for the user.
  977. pw_shell      Unused at this time.
  978.  
  979. Return Values
  980.  
  981. getpwent returns:
  982.  
  983. NULL on failure of EOF.
  984.  
  985. See Also
  986.  
  987. getpwuid, getpwnam, setpwent, getlogin, getuid
  988.  
  989.  getpwuid
  990.  
  991. SYNOPSIS
  992.  
  993. #include <pwd.h>
  994. struct passwd *getpwuid(int uid);
  995.  
  996. DESCRIPTION
  997.  
  998. getpwuid searches the password file sequentially for a pw_uid matching
  999. that specified by the uid parameter. When a match is found, the corresponding
  1000. passwd entry is returned.
  1001.  
  1002. Notes
  1003.  
  1004. The passwd structure is defined in the description for getpwent.
  1005.  
  1006. Return Values
  1007.  
  1008. getpwuid returns:
  1009.  
  1010. NULL on failure.
  1011.  
  1012.  getpwnam
  1013.  
  1014. SYNOPSIS
  1015.  
  1016. #include <pwd.h>
  1017. struct passwd *getpwnam(char *name);
  1018.  
  1019. DESCRIPTION
  1020.  
  1021. getpwuid searches the password file sequentially for a pw_name matching
  1022. that specified by the name parameter. When a match is found, the corresponding
  1023. passwd entry is returned.
  1024.  
  1025. Notes
  1026.  
  1027. The passwd structure is defined in the description for getpwent.
  1028.  
  1029. Return Values
  1030.  
  1031. getpwnam returns:
  1032.  
  1033. Null on failure.
  1034.  
  1035.  getlogin
  1036.  
  1037. SYNOPSIS
  1038.  
  1039. #include <pwd.h>
  1040. char *getlogin(void);
  1041.  
  1042. DESCRIPTION
  1043.  
  1044. getlogin returns the username of the current system user.
  1045.  
  1046. Notes
  1047.  
  1048. Value returned is STATIC and is updated by subsequent calls.
  1049.  
  1050.  getuid
  1051.  
  1052. SYNOPSIS
  1053.  
  1054. #include <pwd.h>
  1055. int getuid(void);
  1056.  
  1057. DESCRIPTION
  1058.  
  1059. getuid returns the user id of the current system user.
  1060.  
  1061. DESQview/X Extension Routines
  1062.  
  1063. In order for an application to use the BSD 4.3 Socket Library, several
  1064. extension routines are needed. These perform the functions of initializing
  1065. and terminating the use of the DESQview/X Berkeley Socket Interface.
  1066. In addition routines are provided to facilitate communication with
  1067. the Network Manager as a daemon process - see the Network Daemons
  1068. Programming Reference for additional details and extension routines.
  1069.  
  1070.  
  1071.  so_init
  1072.  
  1073. SYNOPSIS
  1074.  
  1075. #include <sys\socket.h>
  1076. int so_init(void);
  1077.  
  1078. DESCRIPTION
  1079.  
  1080. so_init is an extension call that initializes the DESQview/X Socket
  1081. Interface and returns the availability of socket resources.
  1082.  
  1083. Notes
  1084.  
  1085. DESQview/X extension call.
  1086.  
  1087. Return Values
  1088.  
  1089. so_init returns 1 on success, 0 on failure.
  1090.  
  1091.  so_exit
  1092.  
  1093. SYNOPSIS
  1094.  
  1095. #include <sys\socket.h>
  1096. void so_exit(void);
  1097.  
  1098. DESCRIPTION
  1099.  
  1100. Uninitializes the socket interface for the DESQview/X process.
  1101.  
  1102. Notes
  1103.  
  1104. DESQview/X extension call.
  1105.  
  1106.  so_setupdaemon
  1107.  
  1108. SYNOPSIS
  1109.  
  1110. #include <sys\socket.h>
  1111. void so_setupdaemon(char *name);
  1112.  
  1113. DESCRIPTION
  1114.  
  1115. The so_setupdaemon call allows a DESQview/X application to assume
  1116. the identity of a network daemon. The 'name' parameter refers to a
  1117. valid entry in the local SERVICES file. Following the call, the application
  1118. can then issue so_daemon calls to check for connections/datagrams--see
  1119. the section Network Daemons Programming Reference for details.
  1120.  
  1121. Notes
  1122.  
  1123. DESQview/X extension call.
  1124.  
  1125.  getpwvar
  1126.  
  1127. SYNOPSIS
  1128.  
  1129. #include <pwd.h>
  1130. char *getpwvar(char *key, char *var);
  1131.  
  1132. DESCRIPTION
  1133.  
  1134. getpwvar returns the ASCIIZ string describing the value indicated
  1135. by parameters var and key. The key parameter indicates the key into
  1136. the password information file and usually indicates a username. The
  1137. var parameter is the variable that has been defined in the password
  1138. information file to hold the value.
  1139.  
  1140. Notes:
  1141.  
  1142. DESQview/X extension call.
  1143.